Crate rkyv

rkyv is a zero-copy deserialization framework for Rust.

Overview

rkyv uses Rust’s powerful trait system to serialize data without reflection. Many zero-copy deserialization frameworks use external schemas and heavily restrict the available data types. By contrast, rkyv allows all serialized types to be defined in code and can serialize a wide variety of types that other frameworks cannot.

rkyv scales to highly-capable as well as highly-restricted environments. Not only does rkyv support “no-std” builds for targets without a standard library implementation, it also supports “no-alloc” builds for targets where allocations cannot be made.

rkyv supports limited in-place data mutation, and so can access and update data without ever deserializing back to native types. When rkyv’s in-place mutation is too limited, rkyv also provides ergonomic and performant deserialization back into native types.

rkyv prioritizes performance, and is one of the fastest serialization frameworks available. All of rkyv’s features can be individually enabled and disabled, so you only pay for what you use. Additionally, all of rkyv’s zero-copy types are designed to have little to no overhead. In most cases, rkyv’s types will have exactly the same performance as native types.

See the rkyv book for guide-level documentation and usage examples.

Components

rkyv has a hash map implementation that is built for zero-copy deserialization, with the same lookup and iteration performance as the standard library hash maps. The hash map implementation is based on Swiss Tables and uses a target-independent version of FxHash to ensure that all targets compute the same hashes.

It also has a B-tree implementation that has the same performance characteristics as the standard library B-tree maps. Its compact representation and localized data storage is best-suited for very large amounts of data.

rkyv supports shared pointers by default, and is able to serialize and deserialize them without duplicating the underlying data. Shared pointers which point to the same data when serialized will still point to the same data when deserialized. By default, rkyv only supports non-cyclic data structures.

Alongside its unchecked API, rkyv also provides optional validation so you can ensure safety and data integrity at the cost of some overhead. Because checking serialized data can generally be done without allocations, the cost of checking and zero-copy access can be much lower than that of traditional deserialization.

rkyv is trait-oriented from top to bottom, and is made to be extended with custom and specialized types. Serialization, deserialization, and validation traits all accept generic context types, making it easy to add new capabilities without degrading ergonomics.

Features

rkyv has several feature flags which can be used to modify its behavior. By default, rkyv enables the std, alloc, and bytecheck features.

Format control

These features control how rkyv formats its serialized data. Enabling and disabling these features may change rkyv’s serialized format, and as such can cause previously-serialized data to become unreadable. Enabling format control features that are not the default should be considered a breaking change to rkyv’s serialized format.

Binaries should consider explicitly choosing format control options from the start, even though doing so is not required. This ensures that developers stay informed about the specific choices being made, and prevents any unexpected compatibility issues with libraries they depend on.

Libraries should avoid enabling format control features unless they intend to only support rkyv when those specific format control features are enabled. In general, libraries should be able to support all format control options if they use rkyv’s exported types and aliases.

Endianness

If an endianness feature is not enabled, rkyv will use little-endian byte ordering by default.

• little_endian: Forces data serialization to use little-endian byte ordering. This optimizes serialized data for little-endian architectures.
• big_endian: Forces data serialization to use big-endian byte ordering. This optimizes serialized data for big-endian architectures.

Alignment

If an alignment feature is not enabled, rkyv will use aligned primitives by default.

• aligned: Forces data serialization to use aligned primitives. This adds alignment requirements for accessing data and prevents rkyv from working with unaligned data.
• unaligned: Forces data serialization to use unaligned primitives. This removes alignment requirements for accessing data and allows rkyv to work with unaligned data more easily.

Pointer width

If a pointer width feature is not enabled, rkyv will serialize isize and usize as 32-bit integers by default.

• pointer_width_16: Serializes isize and usize as 16-bit integers. This is intended to be used only for small data sizes and may not handle large amounts of data.
• pointer_width_32: Serializes isize and usize as 32-bit integers. This is a good choice for most data, and balances the storage overhead with support for large data sizes.
• pointer_width_64: Serializes isize and usize as 64-bit integers. This is intended to be used only for extremely large data sizes and may cause unnecessary data bloat for smaller amounts of data.

Functionality

These features enable more built-in functionality and provide more powerful and ergonomic APIs. Enabling and disabling these features does not change rkyv’s serialized format.

• alloc: Enables support for the alloc crate. Enabled by default.
• std: Enables standard library support. Enabled by default.
• bytecheck: Enables data validation through bytecheck. Enabled by default.

Crates

rkyv provides integrations for some common crates by default. In the future, crates should depend on rkyv and provide their own integration. Enabling and disabling these features does not change rkyv’s serialized format.

• arrayvec-0_7
• bytes-1
• hashbrown-0_14
• indexmap-2
• smallvec-1
• smol_str-0_2
• smol_str-0_3
• thin-vec-0_2
• tinyvec-1
• triomphe-0_1
• uuid-1

Compatibility

Serialized data can be accessed later as long as:

• The underlying schema has not changed
• The serialized format has not been changed by format control features
• The data was serialized by a semver-compatible version of rkyv

Re-exports

• pub use ::bytecheck;
  bytecheck
• pub use ::munge;
• pub use ::ptr_meta;
• pub use ::rancor;
• pub use ::rend;

Modules

• api
  APIs for producing and using archived data.
• boxed
  An archived version of Box.
• collections
  Archived versions of standard library containers.
• de
  Deserialization traits, deserializers, and adapters.
• ffi
  Archived versions of FFI types.
• hash
  Hashing support for archived hash maps and sets.
• net
  Archived versions of network types.
• niche
  Manually niched type replacements.
• ops
  Archived versions of ops types.
• option
  An archived version of Option.
• place
  An initialized, writeable location in memory.
• primitive
  Definitions of archived primitives and type aliases based on enabled features.
• rc
  Archived versions of shared pointers.
• rel_ptr
  Relative pointer implementations and options.
• result
  An archived version of Result.
• seal
  Mutable references to values which may not be moved or de-initialized.
• ser
  Serialization traits and adapters.
• string
  Archived versions of string types.
• time
  Archived versions of time types.
• traits
  The core traits provided by rkyv.
• tuple
  Archived versions of tuple types.
• util
  Utilities for common operations.
• validationbytecheck
  Validation implementations and helper types.
• vec
  An archived version of Vec.
• with
  Wrapper type support and commonly used wrappers.

Structs

• Place
  A place to write a T paired with its position in the output buffer.

Traits

• Archive
  A type that can be used without deserializing.
• ArchiveUnsized
  A counterpart of Archive that’s suitable for unsized types.
• Deserialize
  Converts a type back from its archived form.
• DeserializeUnsized
  A counterpart of Deserialize that’s suitable for unsized types.
• Portable
  A type with a stable, well-defined layout that is the same on all targets.
• Serialize
  Converts a type to its archived form.
• SerializeUnsized
  A counterpart of Serialize that’s suitable for unsized types.

Functions

• accessbytecheck and alloc
  Access a byte slice.
• access_mutbytecheck and alloc
  Mutably access a byte slice.
• access_unchecked^⚠
  Access a byte slice.
• access_unchecked_mut^⚠
  Mutably access a byte slice.
• deserializealloc
  Deserialize a value from the given archived value.
• from_bytesbytecheck and alloc
  Deserialize a value from the given bytes.
• from_bytes_unchecked^⚠alloc
  Deserialize a value from the given bytes.
• to_bytesalloc
  Serialize a value to bytes.

Type Aliases

• Archived
  Alias for the archived version of some Archive type.
• ArchivedMetadata
  Alias for the archived metadata for some ArchiveUnsized type.
• RawRelPtr
  The default raw relative pointer.
• RelPtr
  The default relative pointer.
• Resolver
  Alias for the resolver for some Archive type.

Derive Macros

• Archive
  Derives Archive for the labeled type.
• Deserialize
  Derives Deserialize for the labeled type.
• Portable
  Derives Portable for the labeled type.
• Serialize
  Derives Serialize for the labeled type.